@kitschpatrol/tldraw-cli

@kitschpatrol/tldraw-cli

Overview

A minimal CLI app to automate conversion and export of tldraw URLs and .tldr files into SVG or PNG image formats.

This could be useful in the context of a content publishing pipeline where you want to use a .tldr file (perhaps under version control) as the "source of truth" for assets to be embedded elsewhere, and you don't want to manage the export of that diagram manually.

For .tldr file import support in Vite projects, please see @kitschpatrol/vite-plugin-tldraw.

Installation

Invoke directly:

npx @kitschpatrol/tldraw-cli some-file.tldr

...or install locally:

npm install --save-dev @kitschpatrol/tldraw-cli

...or install globally:

npm install --global @kitschpatrol/tldraw-cli

Command line usage

Invocation

tldraw-cli file-or-url {options}

Argument	Description
file-or-url	The sketch to convert to an image — either a path to a local ".tldr" file, or a tldraw.com sketch URL.

Option	Alias	Description Value	Default Value
--format <svg|png>	-f	Output image format, one of svg or png.	svg
--dark-mode	-d	Output a dark theme version of the image.	false
--transparent	-t	Output an image with a transparent background.	false
--output <string>	-o	Output directory.	./
--name <string>	-n	Output file name without extension; by default the original file name or URL id is used.
--frames <array?>		Export each sketch "frame" as a separate image, use the option flag alone to export all frames, or pass one or more frame names or IDs, slugified frame names will also match.	false
--strip-style		Remove <style> elements from SVG output, useful to lighten the load of embedded fonts or if you are going to provide your own stylesheet for the SVG.	false
--help	-h	Show help.
--version	-v	Show version number.
--verbose		Enable verbose output.	false

Examples

Basic .tldr file conversion

To convert the file your-drawing.tldr to an svg named your-drawing.svg saved in the current working directory, run the following command. Note that the default output format is svg, and the default export location is the current working directory.

npx @kitschpatrol/tldraw-cli your-drawing.tldr

The file will retain its original name, e.g. your-drawing.svg

Basic tldraw.com image download

npx @kitschpatrol/tldraw-cli https://www.tldraw.com/s/v2_c_JsxJk8dag6QsrqExukis4

The tldraw URL's id (e.g. v2_c_JsxJk8dag6QsrqExukis4) will be used for the file name.

Export to a specific format

npx @kitschpatrol/tldraw-cli your-drawing.tldr --format png

Export with a transparent background

npx @kitschpatrol/tldraw-cli your-drawing.tldr --transparent --format png

Export to a specific destination

npx @kitschpatrol/tldraw-cli your-drawing.tldr --output ~/Desktop

Saves to ~/Desktop/your-drawing.svg

Export to a specific destination and filename

npx @kitschpatrol/tldraw-cli your-drawing.tldr --output ~/Desktop --name not-your-drawing

Saves to ~/Desktop/not-your-drawing.svg

Export all frames from a single tldraw URL

npx @kitschpatrol/tldraw-cli https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames

The saved files will be suffixed with their frame name, e.g.:

v2_c_FI5RYWbdpAtjsy4OIKrKw-frame-1.png v2_c_FI5RYWbdpAtjsy4OIKrKw-frame-2.png v2_c_FI5RYWbdpAtjsy4OIKrKw-frame-3.png

The frame name will be slugified.

It's possible in tldraw to give multiple frames in a single sketch the same name. In these cases, the frame ID is used in addition to the name to ensure unique output file names.

Export a specific frame from a tldraw URL

npx @kitschpatrol/tldraw-cli https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw --frames "Frame 1" "Frame 3"

API usage

The conversion tool's functionality is also exposed as a module for use in TypeScript or JavaScript Node projects.

The library exports a single async function, tldrawToImage, which takes an options argument mirroring the arguments available via the command line. The same default values apply:

 tldrawToImage(
  tldrPathOrUrl: string,
  {
    darkMode?: boolean
    output?: string
    format?: 'png' | 'svg'
    frames?: boolean | string[]
    stripStyle?: boolean
    transparent?: boolean
    verbose?: boolean
 }): Promise<string | string[]>;

The function exports the image in the requested format returns the full path to the output image.

Assuming you've installed @kitschpatrol/tldraw-cli locally in your project, it may be used as follows:

// tldr-cli-api-test.ts

import { tldrawToImage } from '@kitschpatrol/tldraw-cli'

// Convert a local file to PNG
const imagePath = await tldrawToImage('./some-file.tldr', { format: 'png', output: './' })
console.log(`Wrote image to: "${imagePath}"`)

// Convert a remote tldraw URL to SVG
await tldrawToImage('https://www.tldraw.com/s/v2_c_JsxJk8dag6QsrqExukis4')

// Convert all frames from a single tldraw URL to separate SVGs
// When the `frames` option is set, the function returns an array
// of resulting file paths, instead of a solitary string
const framePathsArray = await tldrawToImage('https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw', {
  frames: true,
})
console.log(`Wrote frames to: "${framePathsArray}"`)

// Convert a specific frame from a tldraw URL to a PNG
await tldrawToImage('https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw', {
  frames: ['Frame 3'],
  format: 'png',
})

// You can also use the frame id instead of name, if you're into that sort of thing
// It will work with or without the `shape:` prefix
await tldrawToImage('https://www.tldraw.com/s/v2_c_FI5RYWbdpAtjsy4OIKrKw', {
  frames: ['shape:x8z3Qf7Hgw4Qqp2AC-eet'],
})

Note that the library provided is ESM only, and requires a Node-compatible runtime. TypeScript type definitions are included.

Background

The potential utility of a tldraw CLI app has received mention a few times.

On GitHub:

• [Feature]: CLI export application #1491
• AWS Lambda-based approach
• Added exporting of shapes and pages as images
• [feature] Copy/Share as PNG

On Discord:

• @jorisjh in #ideas_old
• @Nitsuj in #ideas_old

Implementation notes

This tool is not a part of the official tldraw project, and it is currently only tested and known to be compatible with tldraw 2.0.0-beta.2._

Due to the current implementation of tldraw, export depends on functionality provided by a web browser. So, behind the scenes, this app serves a local instance of tldraw, then loads a .tldr and invokes the export download via Puppeteer.

This can be a bit slow, (exporting seems to take a second or two), but in the context of a statically-generated content pipeline it's not the end of the world.

In terms of Puppeteer vs. Playwright and other headless browser automation tools, it looks like Puppeteer's performance likely compares favorably. (Though I have not tested and benchmarked the alternatives in the specific context of tldraw-cli.)

The local instance of tldraw includes its assets dependencies, so the tool should work correctly without internet access.

The future

This is a very minimal implementation. Current plans for future improvements include the following:

• Add CLI tests
• Implement the ability to export specific pages as separate image files
• Add an option flag to set dpi when exporting to a bitmap format
• Additional commands beyond sketch conversion / export?

Any other suggestions are welcome.

Eventually, I think it would make sense for some kind of CLI tool like this one to be part of the core tldraw project. (Similar to how tldraw-vscode is currently integrated.)

I'm consciously releasing this tool under the @kitschpatrol namespace on NPM to leave the tldraw-cli package name available to the core tldraw project.